configure (InstantSearch.js v4)

A widget for InstantSearch.js to provide search parameters to Algolia.

The configure widget lets you provide raw search parameters to the Algolia API without rendering anything.

Any props you pass to this widget are forwarded to Algolia.

Usage

configure(searchParameters);

Options

searchParameters · object · required

A list of search parameters to enable.

Connector

To create your own UI for the configure widget, use the connectConfigure comnector.

Import it with a package manager or with a CDN.

Package manager

import { connectConfigure } from 'instantsearch.js/es/connectors';

After importing:

1. Create a render function

   Render functions

   refine · function

   This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

   widgetParams · object

   All original widget options forwarded to the render function.

   refine example

   const renderConfigure = (renderOptions, isFirstRender) => {
       const { refine } = renderOptions;
   
       if (isFirstRender) {
           const button = document.createElement('button');
           button.textContent = 'Sets "hitsPerPage" to 4';
   
           button.addEventListener('click', () => {
           refine({ hitsPerPage: 4 });
           });
   
           document.querySelector('#configure').appendChild(button);
       }
   };
   

2. Create the custom widget

   There are two types of parameters you can give:

   • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
   • Your own parameters: to make the custom widget generic.

   Both are available in connector.widgetParams, inside the render function.

   const customConfigure = connectConfigure(
   renderConfigure
   );
   

3. Instantiate the custom widget

   customConfigure({
       searchParameters: {
           hitsPerPage: 8,
           distinct: true,
           clickAnalytics: true,
       },
   });
   

Example

// Create the render function
const renderConfigure = (renderOptions, isFirstRender) => {
  const { refine, widgetParams } = renderOptions;

  if (isFirstRender) {
    const button = document.createElement('button');
    const pre = document.createElement('pre');

    button.addEventListener('click', () => {
      refine({
        hitsPerPage: widgetParams.searchParameters.hitsPerPage === 8 ? 4 : 8,
      });
    });

    widgetParams.container.appendChild(button);
    widgetParams.container.appendChild(pre);
  }

  widgetParams.container.querySelector(
    'button'
  ).textContent = `Sets "hitsPerPage" to ${
    widgetParams.searchParameters.hitsPerPage === 8 ? 4 : 8
  }`;

  widgetParams.container.querySelector('pre').innerHTML = JSON.stringify(
    widgetParams.searchParameters,
    null,
    2
  );
};

// Create the custom widget
const customConfigure = connectConfigure(
  renderConfigure,
  () => {}
);

// Instantiate the custom widget
search.addWidgets([
  customConfigure({
    container: document.querySelector('#configure'),
    searchParameters: {
      hitsPerPage: 8,
    },
  })
]);